home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / pcbde501.zip / PCBDESC.DOC < prev    next >
Text File  |  1993-01-22  |  10KB  |  240 lines
  1.                            PCBDescribe Version 5.01
  2.                Automatic Upload Description Insertion for PCBoard
  3.  
  4.     Copyright (c) 1993 by Clark Development Co., Inc.  All Rights Reserved
  5.  
  6.  
  7. PCBDESC.EXE checks uploaded files for FILE_ID.DIZ (Description In Zipfile)
  8. files provided by the program author.  If the uploaded file contains a
  9. description file, it will replace the user supplied description with the one
  10. provided in the file.
  11.  
  12. PCBDescribe can optionally append a line to the description showing the number
  13. of files and the dates of both the oldest and the newest files in the archive.
  14.  
  15. PCBDescribe is compatible with the following archive formats and requires the
  16. specified program to unarchive the description files when found:
  17.  
  18.     Compatible With          Requires
  19.     ===============          ========
  20.         .ZIP                 PKUNZIP
  21.         .ARJ                 ARJ
  22.         .LZH                 LHA
  23.         .PAK                 PAK
  24.         .ARC                 PKXARC
  25.  
  26.  
  27. INSTALLING PCBDescribe
  28. ======================
  29. PCBDescribe *REQUIRES* PCBoard version 14.5a or higher BBS software to operate.
  30. Earlier versions of PCBoard, or other BBS software packages are NOT compatible
  31. with PCBDescribe.
  32.  
  33. PCBDescribe is used inside of the PCBTEST.BAT file, which is run to test each
  34. upload to the system.  Place the PCBDESC.EXE file in your default \PCB
  35. directory, and insert the following line into PCBTEST.BAT:
  36.  
  37.          IF %2==UPLOAD PCBDESC %1 %3
  38.  
  39. And it's ready to go.  There is only one option; if you would like to have an
  40. additional line in the description showing the date of the oldest and newest
  41. files in the archive, then use this command instead:
  42.  
  43.          IF %2==UPLOAD PCBDESC /D %1 %3
  44.  
  45. The word "UPLOAD" in the above example is case sensitive.  Make sure you type
  46. it in uppercase letters.  Also make sure that you have a copy each of the
  47. required unarchive programs (PKUNZIP, ARJ, LHA, PAK, PKXARC) according to the
  48. types of files you expect to receive.  These unarchive programs should be
  49. placed either in your default \PCB directory, or in a subdirectory referenced
  50. by your PATH.
  51.  
  52. PCBDescribe can be the first thing in your PCBTEST.BAT file; it will only
  53. operate on ZIP, ARJ, LZH, PAK and ARC files (as well as self-extracting
  54. versions of those files).
  55.  
  56. Beginning with the 2.10 release PCBDescribe will watch for DOS reserved words
  57. such as CON, AUX, PRN, CLOCK$, COMx, LPTx, and, if found in the archive, will
  58. RENAME the file to filename.ZIQ, adding one to the last letter of the filename,
  59. (or filename.ARK or filename.EXF depending on the extension of the file) and it
  60. will then leave a one line addition in the UPDESC file indicating the reason
  61. for the rejecting.  Finally, it will exit to DOS with an errorlevel of 5 to
  62. indicate a problem with the file so that further testing of the file can be
  63. AVOIDED saving the system from a lockup that could occur if you have a testing
  64. program that does not watch for DOS reserved words.  NOTE:  none of the other
  65. functions of PCBDescribe will be performed if a reserved word is found.  You
  66. should write your test batch files so that no other functions are performed by
  67. any other programs either.
  68.  
  69. It is recommended that immediately after the execution of PCBDescribe you
  70. insert a line in the PCBTEST.BAT file that reads:
  71.  
  72.          IF ERRORLEVEL == 5 GOTO END
  73.  
  74. Then have a line at the bottom of the PCBTEST.BAT file that has nothing but
  75. ":END" on it.  This will allow PCBDescribe's errorlevel 5 to signal that the
  76. rest of the testing process should be skipped.
  77.  
  78.  
  79. ERRORLEVEL RETURNS
  80. ==================
  81. PCBDescribe will return errorlevels to your batch file to indicate what it has
  82. done.  These errorlevels can then be tested and used for your own purposes.
  83. Return values are as follows:
  84.  
  85.         0   =   No processing performed
  86.         1   =   File was not a supported archive or contents were damaged
  87.         2   =   Description was updated (due to FILE_ID.DIZ or DESC.SDI)
  88.         3   =   Description was updated (no FILE_ID but dates were added)
  89.         4   =   Found description file but unable to process
  90.         5   =   Found a DOS reserved word, file renamed, description
  91.                 modified, no further actions have been taken nor should be
  92.                 taken by other programs.
  93.  
  94.  
  95. THE DESCRIPTION FILE
  96. ====================
  97. PCBDescribe will accept descriptions contained in FILE_ID.DIZ files found in
  98. the archive being tested.  The FILE_ID.DIZ file is an ASCII text file, and can
  99. contain up to 10 lines of 45 characters each.  The first line of this file is
  100. the program name and version, and the following lines describe the function of
  101. the program.
  102.  
  103. It is recommended that formatting codes (such as ASCII line drawing characters)
  104. NOT be used.  However, beginning with version 4.00 PCBDescribe will now
  105. recognize some forms of 'formatting' by detecting these high ASCII characters
  106. and will attempt to protect formatted lines from being word wrapped.
  107.  
  108. PCBDescribe will also detect and use descriptions contained in DESC.SDI files
  109. if they are present.  No other description file formats are supported.
  110.  
  111.  
  112. =============================================================================
  113. ATTENTION!  The FILE_ID.DIZ file format is intended for the program author's
  114. use in providing a coherent description of his program.  In this way, the
  115. author and the sysop can be assured that the program will be properly described
  116. when uploaded to a BBS.  DO NOT use this file for BBS advertising!
  117. =============================================================================
  118.  
  119.  
  120.  
  121. REVISION HISTORY:
  122.         Version 1.00 - Original Release
  123.  
  124.         Version 1.10 - Maintainence Release
  125.         -----------------------------------
  126.         If a stray description file was left in the default directory,
  127.         PCBDescribe could stick on it.  Fixed.
  128.  
  129.         And to prevent problems for those who insist on using PCBDescribe with
  130.         the wrong BBS software:
  131.         Added testing for improper version of PCBoard software.
  132.         Added testing for proper filespecs on command line.
  133.  
  134.         Updated documentation to include the exit codes returned by PCBDescribe.
  135.  
  136.         Version 1.11 - Bug Fix Release
  137.         ------------------------------
  138.         Error 53 at 4626 caused by incorrect call to PKUNZIP.  Sorry about
  139.         that, folks.  Fixed.
  140.  
  141.         Version 2.00 - Rewrite in C
  142.         ---------------------------
  143.         Made the program both smaller and faster
  144.  
  145.         Fixed a problem with running on Alloy Slave Cards
  146.  
  147.         Changed date line from "Latest File Date in ZIP: MM/DD/YY" to "Files: #
  148.         Oldest: MM/DD/YY  Newest: MM/DD/YY"
  149.  
  150.         Added ERRORLEVEL 2 if a description file was found and processed
  151.  
  152.         PLEASE NOTE:
  153.         ------------
  154.         Previous recommended usage was:   PCBDESC [/D] %1 %3
  155.         Current recommend usage is now:   IF %2 == UPLOAD PCBDESC [/D] %1 %3
  156.  
  157.         The change avoids running PCBDescribe if PCBoard's "TEST" command is being
  158.         used instead of executing an upload test procedure.
  159.  
  160.  
  161.         Version 2.01 - Minor fix
  162.         ------------------------
  163.         Removed the FILE_ID.DIZ or DESC.SDI files after reading them.  Not
  164.         deleting them caused no harm, they could not be re-used, but the
  165.         change was made just to make the running more transparent.
  166.  
  167.  
  168.         Version 2.02 - Minor change
  169.         ---------------------------
  170.         Old errorlevels:
  171.         2     =    Description was updated (file_id or dates added to desc)
  172.         3     =    Found description file but unable to process
  173.  
  174.         New errorlevels:
  175.         2     =    Description was updated (due to FILE_ID.DIZ or DESC.SDI)
  176.         3     =    Description was updated (no FILE_ID but dates were added)
  177.         4     =    Found description file but unable to process
  178.  
  179.         Version 2.03 - Minor fix
  180.         ------------------------
  181.         Errorlevel 3 was being returned to indicate file dates were added to
  182.         the description even if you did not use the /D parameter to insert
  183.         the file dates.  Fixed.
  184.  
  185.  
  186.         Version 2.04 - Minor fix
  187.         ------------------------
  188.         FILE_ID.DIZ files are only supposed to be up to 10 lines in length.  A
  189.         34 line file managed to lock PCBDescribe up.  Fixed.
  190.  
  191.  
  192.         Version 3.00 - Added new capability
  193.         -----------------------------------
  194.         Added the ability to detect and REJECT a zip that has a DOS reserved
  195.         word in it.
  196.  
  197.  
  198.         Version 3.01 - Minor fix
  199.         ------------------------
  200.         PCBDescribe could crash on some OS/2 installations.  The same fix
  201.         that OS2PATCH.ZIP provided for the PCB145.EXE file has been applied
  202.         to the PCBDESC.EXE file.
  203.  
  204.         Version 4.00 - Added new capability
  205.         -----------------------------------
  206.         Added the following abilities:  1) Removal of PCBoard @-macros, 2)
  207.         Removal of control codes, 3) Awareness of certain forms of 'formatting'
  208.         which allows the formatting to remain intact.  Also, improved the
  209.         ability to maximize spacing (when word wrapping) to reduce the number
  210.         of lines in the output.
  211.  
  212.  
  213.         Version 4.01 - Minor fix
  214.         ------------------------
  215.         A lockup could occur upon detection of a PCBoard macro that was not
  216.         completely identified. Fixed.
  217.  
  218.  
  219.         Version 4.02 - Update
  220.         ---------------------
  221.         Added compatibility with PKZIP v2.04c, including self extracting .EXE
  222.         files created using ZIP2EXE (both 'junior size' and full blown).
  223.  
  224.  
  225.         Version 5.00 - Added new capabilities
  226.         -------------------------------------
  227.         Added compatibility with ARJ
  228.         Added compatibility with LHA
  229.         Added compatibility with PAK
  230.         Added compatibility with ARC
  231.  
  232.         PCBDescribe is also compatible with self-extracting versions of each
  233.         archive supported.
  234.  
  235.  
  236.         Version 5.01 - Minor fix
  237.         ------------------------
  238.         Minor tuning of the ARJ routines to make it compatible with the
  239.         beta version of ARJ.
  240.